@opentelemetry/core

What is @opentelemetry/core?

The @opentelemetry/core package is part of the OpenTelemetry project, which provides a set of APIs, libraries, agents, and instrumentation to provide observability for applications. Specifically, the core package includes fundamental building blocks for creating and managing telemetry data (metrics, traces, logs) and is designed to be used by other OpenTelemetry packages to create a complete observability framework.

What are @opentelemetry/core's main functionalities?

Context Management

This feature allows for the propagation of context information across asynchronous operations in your application. The context is used to store and access current execution-specific data, such as active span in tracing.

const { context, ROOT_CONTEXT } = require('@opentelemetry/core');
const ctx = context.active();
const newContext = context.with(ROOT_CONTEXT, () => {});

Propagation

Propagation is used to transmit context (e.g., traces and correlations) across process boundaries. It includes utilities to inject and extract context information from carriers in various formats.

const { propagation, defaultTextMapGetter } = require('@opentelemetry/core');
const carrier = {};
const context = propagation.extract(ROOT_CONTEXT, carrier, defaultTextMapGetter);

Instrumentation

Instrumentation is a core part of OpenTelemetry, allowing developers to collect telemetry data (metrics, logs, and traces) from their applications. This feature provides diagnostic logging capabilities.

const { diag } = require('@opentelemetry/core');
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.INFO);

Other packages similar to @opentelemetry/core

jaeger-client

Jaeger client is a distributed tracing system. It's similar to @opentelemetry/core in that it provides tracing capabilities, but it's specifically designed for use with the Jaeger backend. Unlike OpenTelemetry, which aims to be vendor-neutral, Jaeger client is tailored for Jaeger.

prom-client

Prom-client is a client for the Prometheus monitoring system, focusing on gathering metrics. It's similar to the metrics collection part of @opentelemetry/core but is specifically designed for use with Prometheus rather than being part of a broader observability framework.

README

OpenTelemetry Core

This package provides default implementations of the OpenTelemetry API for trace and metrics. It's intended for use both on the server and in the browser.

Built-in Implementations

• Built-in Propagators
  • HttpTraceContext Propagator
  • B3 Propagator
  • Composite Propagator
• Built-in Sampler
  • Always Sampler
  • Never Sampler
  • Probability Sampler

Built-in Propagators

HttpTraceContext Propagator

OpenTelemetry provides a text-based approach to propagate context to remote services using the W3C Trace Context HTTP headers.

This is used as a default Propagator

const api = require("@opentelemetry/api");
const { HttpTraceContext } = require("@opentelemetry/core");

/* Set Global Propagator */
api.propagation.setGlobalPropagator(new HttpTraceContext());

B3 Propagator

This is propagator for the B3 HTTP header format, which sends a SpanContext on the wire in an HTTP request, allowing other services to create spans with the right context. Based on: https://github.com/openzipkin/b3-propagation

const api = require("@opentelemetry/api");
const { B3Propagator } = require("@opentelemetry/core");

/* Set Global Propagator */
api.propagation.setGlobalPropagator(new B3Propagator());

Composite Propagator

Combines multiple propagators into a single propagator.

const api = require("@opentelemetry/api");
const { CompositePropagator } = require("@opentelemetry/core");

/* Set Global Propagator */
api.propagation.setGlobalPropagator(new CompositePropagator());

Built-in Sampler

Sampler is used to make decisions on Span sampling.

Always Sampler

Samples every trace regardless of upstream sampling decisions.

This is used as a default Sampler

const { NodeTracerProvider } = require("@opentelemetry/node");
const { ALWAYS_SAMPLER } = require("@opentelemetry/core");

const tracerProvider = new NodeTracerProvider({
  sampler: ALWAYS_SAMPLER
});

Never Sampler

Doesn't sample any trace, regardless of upstream sampling decisions.

const { NodeTracerProvider } = require("@opentelemetry/node");
const { NEVER_SAMPLER } = require("@opentelemetry/core");

const tracerProvider = new NodeTracerProvider({
  sampler: NEVER_SAMPLER
});

Probability Sampler

Samples a configurable percentage of traces, and additionally samples any trace that was sampled upstream.

const { NodeTracerProvider } = require("@opentelemetry/node");
const { ProbabilitySampler } = require("@opentelemetry/core");

const tracerProvider = new NodeTracerProvider({
  sampler: new ProbabilitySampler(0.5)
});

Useful links

• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
• For help or feedback on this project, join us on gitter

License

Apache 2.0 - See LICENSE for more information.

Changelog

0.5.2

Released 2020-03-27

:rocket: (Enhancement)

• opentelemetry-exporter-prometheus, opentelemetry-metrics
  • #893 Metrics: Add lastUpdateTimestamp associated with point (@mayurkale22)
• opentelemetry-tracing
  • #896 Do not export empty span lists (@dyladan)
• opentelemetry-api, opentelemetry-tracing
  • #889 feat: start a root span with spanOptions.parent = null (@dyladan)

:bug: (Bug Fix)

• opentelemetry-core, opentelemetry-propagator-jaeger
  • #904 fix: add type checking in propagators (@dyladan)
• opentelemetry-context-base, opentelemetry-core, opentelemetry-plugin-document-load, opentelemetry-plugin-user-interaction, opentelemetry-web
  • #906 chore: fixing documentation for web tracer provider, fixing examples … (@obecny)
• Other
  • #884 chore: fixing main package.json version (@obecny)

:books: (Refine Doc)

• opentelemetry-context-base, opentelemetry-core, opentelemetry-plugin-document-load, opentelemetry-plugin-user-interaction, opentelemetry-web
  • #906 chore: fixing documentation for web tracer provider, fixing examples … (@obecny)

Committers: 4

• Bartlomiej Obecny (@obecny)
• Daniel Dyla (@dyladan)
• Mark Robert Henderson (@aphelionz)
• Mayur Kale (@mayurkale22)